home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat5 / elspec.z / elspec
Encoding:
Text File  |  1998-10-30  |  20.9 KB  |  529 lines
  1.  
  2.  
  3.  
  4. EEEELLLLSSSSPPPPEEEECCCC((((5555))))                                                            EEEELLLLSSSSPPPPEEEECCCC((((5555))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ELSPEC - ELF Layout specification
  10.  
  11. TTTTOOOOPPPPIIIICCCC
  12.      This manpage describes the ELF Layout Specification language implemented
  13.      by lllldddd((((1111)))) which allows users to exactly specify layout of object files,
  14.      programs, and shared objects.
  15.  
  16.  
  17. IIIINNNNTTTTRRRROOOODDDDUUUUCCCCTTTTIIIIOOOONNNN
  18.      It is often desirable to specify the exact layout of an executable file.
  19.      Some of the uses of this might be embedded systems, thread-local data
  20.      layout, reducing cache conflicts, reducing false sharing, reducing memory
  21.      utilization.  The current linker allows exact specification of layout via
  22.      the ELF Layout Specification language.
  23.  
  24.  
  25.    IIIInnnnvvvvooookkkkiiiinnnngggg LLLLaaaayyyyoooouuuutttt SSSSppppeeeecccciiiiffffiiiiccccaaaattttiiiioooonnnn
  26.      An elspec file is specified to the linker using
  27.  
  28.           cc -Wl,-elspec,<filename> ...
  29.           or
  30.           ld -elspec <filename> ...
  31.  
  32.      You may get a sample elspec file for the default link using:
  33.  
  34.           cc -Wl,-elsmap ...
  35.           or
  36.           ld -elsmap ...
  37.  
  38.  
  39.    BBBBaaaassssiiiicccc BBBBuuuuiiiillllddddiiiinnnngggg BBBBlllloooocccckkkkssss
  40.      The basic units that the linker manipulates are called _i_n_p_u_t _s_e_c_t_i_o_n_s.
  41.      Each object file may have several of these, with familiar names such as
  42.      `.text', `.data', `.bss', and so on.  The correctness of compiled code
  43.      may depend on the exact layout of a section, but never depends on the
  44.      relative layout between sections.  For that reason, the linker will never
  45.      rearrange or change the contents of any individual input section in any
  46.      way.
  47.  
  48.      The one exception to this are COMMON variables, for which space is
  49.      allocated by the linker, and as such, are not allocated to any input
  50.      section. These can be manipulated freely, but not split into pieces by
  51.      ELF Layout Specification.  You get a COMMON variable by using a FORTRAN
  52.      COMMON, or from C data variables declared at file scope in files which
  53.      have been compiled with either ----cccccccckkkkrrrr or ----ccccoooommmmmmmmoooonnnn....
  54.  
  55.  
  56.    SSSSeeeeggggmmmmeeeennnnttttssss
  57.      Input sections are linked together more or less contiguously into output
  58.      sections.  Output sections are organized in and ELF file into loadable
  59.      _s_e_g_m_e_n_t_s which are specified in the program header. See eeeellllffff((((5555)))).... Segments
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. EEEELLLLSSSSPPPPEEEECCCC((((5555))))                                                            EEEELLLLSSSSPPPPEEEECCCC((((5555))))
  71.  
  72.  
  73.  
  74.      represent a contiguous portion of the file which is to be loaded into
  75.      memory as-is, with possibly the addition of extra memory at the end.
  76.  
  77.  
  78.    PPPPllllaaaacccceeeemmmmeeeennnntttt RRRRuuuulllleeeessss
  79.      ELF Layout Specification works by allowing the user to specify the
  80.      placement of input sections within output sections, and the output
  81.      sections within segments.  In order to avoid requiring the user to
  82.      specify every input file, we give rules for the default placement of an
  83.      input section in an output section and the placement of output sections
  84.      within segments.
  85.  
  86.      A section from an input file will be placed in the output file according
  87.      to these rules:
  88.  
  89.      1. If the section (and object and archive) are mentioned explicitly,
  90.         place it there.
  91.  
  92.      2. If there is a section specified in the map with the same name,
  93.         which has "default" as one of its contents, and which has matching
  94.         attributes, place it there. The input section will maintain
  95.         its layout position relative to other listed contents.  If there
  96.         is more than one default-placed input section, they will be
  97.         allocated space in the order encountered.  If the attributes of the
  98.         input section do not match those specified in the map, it is an error.
  99.  
  100.      3. If there is a segment specified in the map with matching attributes
  101.         which has specified "default" as one of its contents,
  102.         the input section will be placed in an output section with the same
  103.         name and attributes. The input section will maintain
  104.         its layout position relative to other listed contents.  If there
  105.         is more than one default-placed input section, they will be
  106.         allocated space in the order encountered.  If the attributes of the
  107.         input section do not match those specified in the map or those of
  108.         another default input section, it is an error.
  109.  
  110.      4. If an input object is listed as a segment content
  111.         without mention of specific input sections, all sections with
  112.         appropriate attributes are merged by name and laid out in the order
  113.         encountered.
  114.  
  115.      5. File layout will be managed by the linker in any fashion it sees
  116.         fit. We can provide a flag -ignorevce to allow tighter packing.
  117.  
  118.      6. Specifying "headers" as contents of a segment allows (but does not
  119.         require) the inclusion of headers such as the ELF header and the
  120.         program header into that segment.  Specifying "default" has this
  121.         effect as well.  Specifying "noheaders" will forbid the inclusion
  122.         of headers into that segment
  123.  
  124.      7. Loader-generated sections will be placed in to a segment with matching
  125.         attributes which has specified "ldgen" as its segment contents.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. EEEELLLLSSSSPPPPEEEECCCC((((5555))))                                                            EEEELLLLSSSSPPPPEEEECCCC((((5555))))
  137.  
  138.  
  139.  
  140.         Specific loader-generated sections may be placed by using $ldobj as
  141.         the object name.  When a non-optional loader-generated section has
  142.         no place to be loaded, an error is generated, unless the global switch
  143.        "$ignoreldgen" has the value "true".
  144.  
  145.      8. Should user-specified alignment result in R4000 alignment problems,
  146.         ld will report these to the user, and produce output anyway.  If
  147.         "$r4kbugfix" is set to false (or -allow_jump_at_eop specfied on the
  148.         linkline), no checking will be performed.
  149.  
  150.      9. In general, command line options take precedence over
  151.         specifications here.
  152.  
  153.      10.Overlaps in virtual space or physical space will be reported
  154.         unless at least one of the segment descriptions has specified an
  155.         overlap with the other, or unless "$ignoreoverlaps" is true.
  156.  
  157.      11.The name, type, and flags of an output section uniquely determines
  158.         that section. Specifying more than one such section in the file
  159.         will yield unpredictable results.
  160.  
  161.      12.Sections with flags SHF_ALLOC and SHF_READ but not SHF_WRITE, will be
  162.         placed in the first segment which has PF_R but not PF_W set.
  163.  
  164. SSSSYYYYNNNNTTTTAAAAXXXX
  165.      This section describes the actual syntax of an ELSPEC file.  There are
  166.      some examples at the end.
  167.  
  168.  
  169.    OOOOvvvveeeerrrrvvvviiiieeeewwww
  170.      There are three main parts to the layout specification (lspec) file.  In
  171.      order expected, they are: a list of global variable settings, a list of
  172.      symbols attribute specifications, and a list of segment specifications.
  173.  
  174.                <layoutspec> ::= <globals> <symlist> <seglist>;
  175.  
  176.  
  177.    SSSSeeeeggggmmmmeeeennnnttttssss
  178.      Segments are the basic runtime building blocks.  They are necessarily
  179.      contiguous, both in memory and in the file.  They have a uniform set of
  180.      protections associated.
  181.  
  182.                <segdef> ::= beginseg <segname> <segattr>
  183.                                <segspecial> contents <segcontents> endseg;
  184.  
  185.                <segname> ::= /* empty */ | name <idstring>;
  186.  
  187.                <segattr> ::= /* empty */
  188.                          | <segattr> segtype <segtype>
  189.                          | <segattr> vaddr <address>
  190.                          | <segattr> paddr <address>
  191.                          | <segattr> segflags <segflags>
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. EEEELLLLSSSSPPPPEEEECCCC((((5555))))                                                            EEEELLLLSSSSPPPPEEEECCCC((((5555))))
  203.  
  204.  
  205.  
  206.                         | <segattr> segalign <number>
  207.                       ;
  208.  
  209.                <segtype> ::= noload /* include in output segment */
  210.                           | <number>
  211.                           | LOAD /* this is the default */
  212.                        | REL
  213.                        ;
  214.  
  215.                <segflags> ::= /* empty, default settings are RWX */
  216.                          | <segflags> R /* Set the PF_R flag */
  217.                       | <segflags> W /* Set the PF_W flag */
  218.                       | <segflags> X /* Set the PF_X flag */
  219.                       | <segflags> L;/* Set the PF_MIPS_LOCAL flag */
  220.  
  221.      For programs under the IRIX 5.3 and above, segments with the
  222.      PF_MIPS_LOCAL flag set will be thread-local and not shared in the event
  223.      of an sssspppprrrroooocccc((((2222)))) system call.  For other applications, the meaning of this
  224.      bit is undefined.
  225.  
  226.  
  227.    SSSSeeeeggggmmmmeeeennnntttt ccccoooonnnntttteeeennnnttttssss
  228.      Contents of a segment are usually in the form of output sections.  These
  229.      section are further specified to contain input sections (see below), and
  230.      are laid out in the order specified.  The default is to build upwards in
  231.      virtual address space.
  232.  
  233.      Specifying "default" as segment contents allows the linker to place input
  234.      sections with compatible attributes which are not otherwise mentioned in
  235.      the current segment.  This is accomplished by creating a distinct output
  236.      sections for each unique set of section type, flags, and section name,
  237.      and placing it in the "best" segment which has specified "default" as one
  238.      of its segment contents.
  239.  
  240.                <segcontents> ::= /* empty */
  241.                          | <segcontents> <outsection>
  242.                          | <segcontents> noheaders
  243.                          | <segcontents> default;
  244.  
  245.    OOOOuuuuttttppppuuuutttt sssseeeeccccttttiiiioooonnnnssss
  246.      Output sections are a convenient way to group material within a segment.
  247.      For example, we may wish to have read-only data and program text in the
  248.      same segment, but within that segment we want to have all the read-only
  249.      data together and all the text together.  We define two output sections
  250.      named ".rdata" and ".text" and place them both within a single segment.
  251.  
  252.                <outsection> ::= beginscn <idstring> <scnattr> <scnspecial>
  253.                          <scncontents> endscn
  254.                     | beginscn <idstring> relfor <idstring> endscn
  255.                     | beginscn <idstring> relafor <idstring> endscn
  256.                     ;
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. EEEELLLLSSSSPPPPEEEECCCC((((5555))))                                                            EEEELLLLSSSSPPPPEEEECCCC((((5555))))
  269.  
  270.  
  271.  
  272.               <scnattr> ::= /* empty string */
  273.                     | <scnattr> scntype <scntype>
  274.                     | <scnattr> scnflags <scnflags>
  275.                     | <scnattr> scnsize <size>
  276.                     | <scnattr> link <number>
  277.                     | <scnattr> info <number
  278.                     | <scnattr> scnalign <number>
  279.                     | <scnattr> entsize <number>
  280.                     ;
  281.  
  282.                <scntype> ::= PROGBITS | NOTE | NOBITS | <number>;
  283.  
  284.                <scnflags> ::= <scnflaglist> | <number> | none;
  285.  
  286.                <scnflaglist> ::= /* empty */
  287.                     | <scngflaglist> WRITE
  288.                     | <scnflaglist> ALLOC
  289.                     | <scnflaglist> EXECINSTR
  290.                     | <scnflaglist> GPREL
  291.                     | <scnflaglist> MERGE
  292.                     | <scnflaglist> ADDR
  293.                     | <scnflaglist> NOSTRIP
  294.                     | <scnflaglist> LOCAL;
  295.  
  296.      Layout specification for relocatable ("-r") links is supported.  Unlike
  297.      other types of output sections, the contents of relocation sections
  298.      cannot be freely specified.  Rather, the contents of a given "relfor"
  299.      section are determined relative to some other output section.  For
  300.      example, the section specified by
  301.                beginscn .rel.mytext relfor .mytext endscn
  302.      contains all the Rel-type relocations for the output section named
  303.      ".mytext".  Relocation sections can be given any name, but the relocation
  304.      must be preceded by the section the relocations are relative to.
  305.  
  306.    IIIInnnnppppuuuutttt sssseeeeccccttttiiiioooonnnnssss
  307.      Input sections are the basic building blocks which the linker
  308.      manipulates.  Each object file read by the linker may contain several of
  309.      these input section.  The lspec file works by specifying the arrangement
  310.      of these input sections.  Input sections may be specified in two basic
  311.      ways.  The user may attempt to specify the section directly, or may
  312.      specify an external symbol name, which has the effect of specifying the
  313.      section in which that symbol definition resides.
  314.  
  315.                <scncontents> ::= /* Nothing */
  316.                          | <scncontents> default
  317.                          | <scncontents> <inputscn>
  318.                          | <scncontents> <symspec>;
  319.  
  320.      In the rule below, the <_i_d_s_t_r_i_n_g> specifies the name of the input
  321.      section. If no name is specified, all sections from the mentioned object
  322.      with matching attributes are selected.
  323.  
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. EEEELLLLSSSSPPPPEEEECCCC((((5555))))                                                            EEEELLLLSSSSPPPPEEEECCCC((((5555))))
  335.  
  336.  
  337.  
  338.      Sometimes it may occur that the attributes of an input section are not
  339.      compatible with those of the enclosing output section.  Below you see
  340.      different input section specifications categorized as either specific or
  341.      generic.  If a specific mention conflicts with default output section
  342.      attributes, the output section attributes are promoted to be compatible.
  343.      If a specific mention conflicts with user-specified output section
  344.      attributes, the input section is included with a warning, but the output
  345.      section attributes are not altered.  If a generic mention conflicts with
  346.      output section attributes, the input section is not included in the
  347.      output section, regardless of whether the output sections attributes were
  348.      user-specified or not.
  349.  
  350.                <inputscn> ::= sec <idstring> /* specific mention */
  351.                               | sec <idstring> in <object> /* specific mention */
  352.                               | <object>; /* generic mention */
  353.  
  354.                <object> ::= obj[ect] <idstring> ( <idstring> )
  355.                        /* archive(filename) */
  356.                           | obj[ect] <idstring>
  357.                           | ar[chive] <idstring>
  358.                           | ldobj;
  359.                        /* for specifying loader-defined sections */
  360.  
  361.                <symspec> ::=  sym <idstring> in <inputscn>
  362.                             | sym <idstring>;
  363.  
  364.    EEEELLLLSSSSppppeeeecccc VVVVaaaarrrriiiiaaaabbbblllleeeessss
  365.      Various ELF layout Specification (ELSpec) variables can be given values.
  366.      These values will be used by the linker when laying out your program.
  367.  
  368.                <globals> ::= /* NULL */ | globals set_global;
  369.  
  370.                <set_global ::= <gsize> = <size>
  371.                          | <gbool> = <boolean>;
  372.  
  373.                <gsize> ::=    $blocksize
  374.                          | $cachesize
  375.                          | $pagesize
  376.                          | $cachelinesize;
  377.  
  378.                <gbool> ::=    $ignoreldgen
  379.                          | $r4kbugfix
  380.                          | $ignoreoverlaps;
  381.  
  382.    SSSSeeeeggggmmmmeeeennnntttt SSSSppppeeeecccciiiiaaaallll aaaattttttttrrrriiiibbbbuuuutttteeeessss
  383.      These allow users to specify special attributes of a segment.
  384.  
  385.      Specifying "ascending" means that the components will be laid out in
  386.      order of increasing address, beginning at the specified (or default)
  387.      address. This is the default behavior.
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                                                                         PPPPaaaaggggeeee 6666
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400. EEEELLLLSSSSPPPPEEEECCCC((((5555))))                                                            EEEELLLLSSSSPPPPEEEECCCC((((5555))))
  401.  
  402.  
  403.  
  404.      Specifying "overlap <idstring>" denotes that the normal linker checking
  405.      for overlaps in virtual address are not to be performed between the
  406.      current segment and the segment named by <idstring>.  This is to
  407.      facilitate overlay links.
  408.  
  409.                <segspecial> ::= /* empty */
  410.                          | <segspecial> ascending
  411.                          | <segspecial> overlap <idstring>;
  412.  
  413.    BBBBaaaasssseeee DDDDaaaattttaaaa TTTTyyyyppppeeeessss
  414.      Here is the syntax for numbers, booleans, strings and so on.
  415.                <size> ::= <number> | <number> K | <number> M
  416.                <address> ::= <number>
  417.                <number> ::=   0x[0-9a-f]+ /* Hex number */
  418.                          | 0[0-7]+ /* Octal number */
  419.                          | [0-9]+  /* decimal number */
  420.  
  421.                <boolean> ::= true | false;
  422.                <idstring> ::= [a-zA-Z0-9$_.]+
  423.                          | "<any string>";
  424.  
  425.    CCCCoooommmmmmmmeeeennnnttttssss
  426.      If the character '#' appears in a layout specification (except when with
  427.      in a string specified with ""), the remainder of the line, including the
  428.      '#' will be treated as a comment and ignored.
  429.  
  430.  
  431. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  432.    DDDDeeeeffffaaaauuuulllltttt lllliiiinnnnkkkk ssssppppeeeecccc
  433.           #
  434.           #  This is the default link spec.  Using it should give the
  435.           #  same result as not using -elspec
  436.           #
  437.  
  438.           beginseg
  439.                name text
  440.                segtype LOAD
  441.                vaddr 0x10000000
  442.                segflags R X
  443.                segalign 0x10000
  444.  
  445.                contents default
  446.           endseg
  447.           beginseg
  448.                name data
  449.                segtype LOAD
  450.                segflags R W X
  451.                segalign 0x1000
  452.  
  453.                contents default
  454.           endseg
  455.           beginseg
  456.  
  457.  
  458.  
  459.                                                                         PPPPaaaaggggeeee 7777
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466. EEEELLLLSSSSPPPPEEEECCCC((((5555))))                                                            EEEELLLLSSSSPPPPEEEECCCC((((5555))))
  467.  
  468.  
  469.  
  470.               name noload
  471.                segtype noload
  472.  
  473.                contents default
  474.           endseg
  475.  
  476.    AAAAlllliiiiggggnnnniiiinnnngggg aaaa CCCCOOOOMMMMMMMMOOOONNNN ssssyyyymmmmbbbboooollll
  477.           #
  478.           # This link spec will give the COMMON symbol a_ an alignment of 128
  479.           # bytes.  This can be useful to prevent false sharing, among other
  480.           # things.
  481.           #
  482.  
  483.           beginseg
  484.               segtype LOAD
  485.               segflags R X
  486.           #   vaddr 0x10000000
  487.               segalign 0x1000
  488.               contents default
  489.           endseg
  490.  
  491.           beginseg
  492.               segtype LOAD
  493.               segflags R W
  494.           #   vaddr 0x10011000
  495.               segalign 0x1000
  496.               contents default
  497.               beginscn .mybss
  498.                   scntype NOBITS
  499.                   scnflags ALLOC WRITE
  500.                   scnalign 0x80
  501.                   sym a_
  502.               endscn
  503.           endseg
  504.  
  505.  
  506. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  507.      ld(1), elf(5), elfdump(5)
  508.  
  509. UUUUPPPPDDDDAAAATTTTEEEESSSS
  510.      This manpage is updated periodically, the last update was on 3/1/95 for
  511.      IRIX 6.0.2
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.                                                                         PPPPaaaaggggeeee 8888
  526.  
  527.  
  528.  
  529.